STAC-22568: Adding dashboard command #109

viliakov · 2025-08-21T20:07:19Z

New Commands:

dashboard list - List all dashboards with table/JSON output
dashboard describe - Export dashboard JSON with optional file output
dashboard clone - Clone dashboards with custom name/description/scope
dashboard apply - Create/update dashboards from JSON files
dashboard edit - Interactive dashboard editing via system editor
dashboard delete - Delete dashboards by ID or identifier

Features:

Consistent flag validation across all commands (ID/identifier mutual exclusion)
JSON and text output formats supported
File I/O operations for describe/apply commands
Interactive editing with change detection
Experimental feature gating (STS_EXPERIMENTAL_DASHBOARD=1)

Usage

  # Set experimental flag (required for all dashboard commands)
  export STS_EXPERIMENTAL_DASHBOARD=1

  # List all dashboards
  sts dashboard list
  sts dashboard list --output json

  # View dashboard details
  sts dashboard describe --id 1234567890
  sts dashboard describe --identifier "urn:custom:dashboard:my-dashboard" --file dashboard.json

  # Clone a dashboard
  sts dashboard clone --id 1234567890 --name "my-new-dashboard"
  sts dashboard clone --id 1234567890 --name "private-copy" --scope privateDashboard

  # Create dashboard from JSON file
  sts dashboard apply --file new-dashboard.json

  # Edit dashboard interactively
  sts dashboard edit --id 1234567890
  EDITOR=code sts dashboard edit --identifier "urn:custom:dashboard:my-dashboard"

  # Delete dashboard
  sts dashboard delete --id 1234567890
  sts dashboard delete --identifier "urn:custom:dashboard:my-dashboard"

Testing:

Full unit test coverage for all commands
Manual testing verified against live StackState instance

viliakov · 2025-08-22T13:54:48Z

Dashboard CLI Commands - Manual Testing Results by Agent

Date: 2025-08-22

1. Dashboard List Command

Basic Functionality

go run main.go dashboard list
- Shows table with columns: ID, IDENTIFIER, NAME, DESCRIPTION, SCOPE ✅
- Dashboards are sorted by identifier ✅
- All visible dashboards are displayed ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard list
$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard list
ID              | IDENTIFIER                                                | NAME                         | DESCRIPTION                                     | SCOPE
124291188225796 | urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc | test-apply-dashboard-updated | Updated dashboard description via apply command | privateDashboard
199184984075103 | urn:custom:dashboard:075b2e37-c59b-4abb-b9eb-50201bee6402 | dashboard-name               | dashboard description 2                         | publicDashboard
118762123067505 | urn:custom:dashboard:166181bf-4468-4a80-8d4d-9fb643263d06 | test-clone-desc              | Custom description                              | publicDashboard
71119196500053  | urn:custom:dashboard:1cc76677-24fa-4c30-b13f-7f673a9106f4 | test-clone-full              | Full test                                       | privateDashboard
77906455245601  | urn:custom:dashboard:1eb81866-bdd0-4051-8d90-72f637d771fb | test-clone-public            | dashboard description                           | publicDashboard
63410966880     | urn:custom:dashboard:2a63f4a6-cb28-4d94-9277-eb2d136d03a4 | test-clone-public            | dashboard description                           | publicDashboard
40143328578960  | urn:custom:dashboard:48f091d1-3d2c-4266-a33d-744da3ec4c2c | apply-test-dashboard         | Dashboard created via apply command             | publicDashboard

Output Formats

go run main.go dashboard list --output json
- Returns valid JSON format ✅
- Contains dashboards array with dashboard objects ✅
go run main.go dashboard list --output text (default)
- Shows formatted table output ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard list --output json
{
  "dashboards": [
    {
      "_type": "DashboardReadMetadataSchema",
      "description": "Updated dashboard description via apply command",
      "id": 124291188225796,
      "identifier": "urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc",
      "lastUpdateTimestamp": 1755774382662,
      "name": "test-apply-dashboard-updated",
      "ownerId": 253353873643863,
      "scope": "privateDashboard"
    }
    // [Additional 11 dashboards in array]
  ]
}

Error Handling

go run main.go dashboard list --help
- Shows help message with usage instructions ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard list --help
List all dashboards.

Minimum supported StackState version: 5.0.0

Usage:
  sts dashboard list [flags]

Flags:
  -h, --help   help for list

Global Flags:
      --api-token string             Specify the API token of the StackState server
      ...

2. Dashboard Describe Command

Basic Functionality

go run main.go dashboard describe --id 124291188225796
- Returns full dashboard JSON structure ✅
- Includes all fields: _type, id, identifier, name, description, scope, dashboard content ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard describe --id 124291188225796
{
  "_type": "DashboardReadFullSchema",
  "dashboard": {
    "spec": {
      "layouts": [
        {
          "kind": "Grid",
          "spec": {
            "items": []
          }
        }
      ],
      "panels": {}
    }
  },
  "description": "Updated dashboard description via apply command",
  "id": 124291188225796,
  "identifier": "urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc",
  "lastUpdateTimestamp": 1755774382662,
  "name": "test-apply-dashboard-updated",
  "ownerId": 253353873643863,
  "scope": "privateDashboard"
}

go run main.go dashboard describe --identifier "urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc"
- Returns same dashboard as ID test above ✅
- JSON structure is identical ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard describe --identifier "urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc"
{
  "_type": "DashboardReadFullSchema",
  "dashboard": {
    "spec": {
      "layouts": [
        {
          "kind": "Grid",
          "spec": {
            "items": []
          }
        }
      ],
      "panels": {}
    }
  },
  "description": "Updated dashboard description via apply command",
  "id": 124291188225796,
  "identifier": "urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc",
  "lastUpdateTimestamp": 1755774382662,
  "name": "test-apply-dashboard-updated",
  "ownerId": 253353873643863,
  "scope": "privateDashboard"
}

File Output

go run main.go dashboard describe --id 124291188225796 --file /tmp/dashboard_test.json
- Creates file at specified path ✅
- Shows success message with file path ✅
- File contains valid JSON dashboard data ✅
- cat /tmp/dashboard_test.json shows readable JSON ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard describe --id 124291188225796 --file /tmp/dashboard_test.json
✅ Dashboard exported to: /tmp/dashboard_test.json

$ cat /tmp/dashboard_test.json
{
  "_type": "DashboardReadFullSchema",
  "dashboard": {
    "spec": {
      "layouts": [
        {
          "kind": "Grid",
          "spec": {
            "items": []
          }
        }
      ],
      "panels": {}
    }
  },
  "description": "Updated dashboard description via apply command",
  "id": 124291188225796,
  "identifier": "urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc",
  "lastUpdateTimestamp": 1755774382662,
  "name": "test-apply-dashboard-updated",
  "ownerId": 253353873643863,
  "scope": "privateDashboard"
}

Output Formats

go run main.go dashboard describe --id 124291188225796 --output json
- Returns structured JSON with data and format fields ✅
go run main.go dashboard describe --id 124291188225796 --output text (default)
- Returns raw JSON dashboard data ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard describe --id 124291188225796 --output json
{
  "data": "{\n  \"_type\": \"DashboardReadFullSchema\",\n  \"dashboard\": {\n    \"spec\": {\n      \"layouts\": [\n        {\n          \"kind\": \"Grid\",\n          \"spec\": {\n            \"items\": []\n          }\n        }\n      ],\n      \"panels\": {}\n    }\n  },\n  \"description\": \"Updated dashboard description via apply command\",\n  \"id\": 124291188225796,\n  \"identifier\": \"urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc\",\n  \"lastUpdateTimestamp\": 1755774382662,\n  \"name\": \"test-apply-dashboard-updated\",\n  \"ownerId\": 253353873643863,\n  \"scope\": \"privateDashboard\"\n}",
  "format": "json"
}

Error Handling

go run main.go dashboard describe
- Shows error about missing required flags ✅
- Shows help usage ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard describe
❌ One of the required flags {id | identifier} not set

go run main.go dashboard describe --help
- Shows help with flag descriptions ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard describe --help
Describe a dashboard in StackState Templated YAML.

Minimum supported StackState version: 5.0.0

Usage:
  sts dashboard describe { --id ID | --identifier IDENTIFIER } [flags]

Flags:
  -f, --file string         Path to the output file
  -h, --help                help for describe
      --id int              ID of the dashboard
      --identifier string   Identifier (URN) of the dashboard

Global Flags:
      --api-token string             Specify the API token of the StackState server
      ...

3. Dashboard Clone Command

Basic Functionality

go run main.go dashboard clone --id 124291188225796 --name "manual-test-clone"
- Creates new dashboard successfully ✅
- Shows success message with new dashboard ID and name ✅
- New dashboard appears in dashboard list ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard clone --id 124291188225796 --name "manual-test-clone"
✅ Dashboard cloned successfully! New dashboard ID: 46319049594379, Name: manual-test-clone

go run main.go dashboard clone --identifier "urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc" --name "manual-test-clone-2"
- Creates dashboard using identifier instead of ID ✅
- Works identically to ID-based clone ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard clone --identifier "urn:custom:dashboard:057a7ff0-e081-48ea-b7da-b5c065e440dc" --name "manual-test-clone-2"
✅ Dashboard cloned successfully! New dashboard ID: 12792522987115, Name: manual-test-clone-2

Optional Parameters

Basic cloning functionality works ✅
Scope validation properly enforces "publicDashboard" or "privateDashboard" only ✅
Error messages are clear and helpful ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard clone --id 124291188225796 --name "manual-test-scope-fail" --scope "invalid"
❌ Invalid scope: invalid. Must be 'publicDashboard' or 'privateDashboard'

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard clone --id 124291188225796 --name "manual-test-private" --scope "privateDashboard"
✅ Dashboard cloned successfully! New dashboard ID: 94079602342608, Name: manual-test-private

4. Dashboard Delete Command

Basic Functionality

Delete functionality works correctly ✅
Shows appropriate success message ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard delete --id 46319049594379
✅ Dashboard deleted: 46319049594379

5. Dashboard Apply Command

Create New Dashboard

Apply command creates new dashboards successfully ✅
Accepts valid JSON dashboard definitions ✅
Shows appropriate success message with ID and name ✅

$ cat > /tmp/manual_test_dashboard.json << 'EOF'
{
  "name": "manual-test-apply",
  "description": "Dashboard created during manual testing",
  "scope": "publicDashboard",
  "dashboard": {
    "spec": {
      "layouts": [
        {
          "kind": "Grid",
          "spec": {
            "items": []
          }
        }
      ],
      "panels": {}
    }
  }
}
EOF

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard apply --file /tmp/manual_test_dashboard.json
✅ Dashboard created successfully! ID: 115140946305302, Name: manual-test-apply

6. Dashboard Edit Command

Basic Functionality (No Changes)

Edit command opens dashboard JSON correctly ✅
Detects when no changes are made ✅
Shows appropriate warning message ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && EDITOR=cat go run main.go dashboard edit --id 115140946305302
{
  "_type": "DashboardReadFullSchema",
  "dashboard": {
    "spec": {
      "layouts": [
        {
          "kind": "Grid",
          "spec": {
            "items": []
          }
        }
      ],
      "panels": {}
    }
  },
  "description": "Dashboard created during manual testing",
  "id": 115140946305302,
  "identifier": "urn:custom:dashboard:60b38960-ac87-436a-80c4-7cf8a1404c6b",
  "lastUpdateTimestamp": 1755867480683,
  "name": "manual-test-apply",
  "ownerId": 253353873643863,
  "scope": "publicDashboard"
}
⚠️ No changes made

7. General Command Tests

Main Dashboard Command

go run main.go dashboard
- Shows all available subcommands ✅
- Lists: apply, clone, delete, describe, edit, list ✅
- Shows usage information ✅

$ export STS_EXPERIMENTAL_DASHBOARD=1 && go run main.go dashboard
Manage, test and develop dashboards.

Usage:
  sts dashboard [command]

Available Commands:
  apply       Create or edit a dashboard from JSON
  clone       Clone a dashboard
  delete      Delete a dashboard
  describe    Describe a dashboard in STY format
  edit        Edit a dashboard
  list        List all dashboards

Use "sts dashboard [command] --help" for more information about a command.

deontaljaard

LGTM

viliakov force-pushed the STAC-22568 branch from 68c17de to a0e9da3 Compare August 22, 2025 11:18

STAC-22568: Adding dashboard command

2749e4b

viliakov force-pushed the STAC-22568 branch from a0e9da3 to 2749e4b Compare August 25, 2025 08:55

deontaljaard approved these changes Aug 25, 2025

View reviewed changes

viliakov merged commit 1d1d0b3 into main Aug 25, 2025
5 checks passed

viliakov deleted the STAC-22568 branch August 25, 2025 11:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

STAC-22568: Adding dashboard command #109

STAC-22568: Adding dashboard command #109

Uh oh!

viliakov commented Aug 21, 2025 •

edited

Loading

Uh oh!

viliakov commented Aug 22, 2025 •

edited by rb3ckers

Loading

Uh oh!

deontaljaard left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

STAC-22568: Adding dashboard command #109

STAC-22568: Adding dashboard command #109

Uh oh!

Conversation

viliakov commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

viliakov commented Aug 22, 2025 • edited by rb3ckers Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dashboard CLI Commands - Manual Testing Results by Agent

1. Dashboard List Command

Basic Functionality

Output Formats

Error Handling

2. Dashboard Describe Command

Basic Functionality

File Output

Output Formats

Error Handling

3. Dashboard Clone Command

Basic Functionality

Optional Parameters

4. Dashboard Delete Command

Basic Functionality

5. Dashboard Apply Command

Create New Dashboard

6. Dashboard Edit Command

Basic Functionality (No Changes)

7. General Command Tests

Main Dashboard Command

Uh oh!

deontaljaard left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

viliakov commented Aug 21, 2025 •

edited

Loading

viliakov commented Aug 22, 2025 •

edited by rb3ckers

Loading